Skunkware 5/Skunkware 5.iso/man/cat.1/perlovl.1

Text File | 1995-07-25 | 21KB | 463 lines

     PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))  UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000))))  PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))



     NNNNAAAAMMMMEEEE
          perlovl - perl overloading semantics

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
              package SomeThing;

              %OVERLOAD = (
                  '+' => \&myadd,
                  '-' => \&mysub,
                  # etc
              );
              ...

              package main;
              $a = new SomeThing 57;
              $b=5+$a;


     CCCCAAAAVVVVEEEEAAAATTTT SSSSCCCCRRRRIIIIPPPPTTTTOOOORRRR
          Overloading of operators is a subject not to be taken
          lightly.  Neither its precise implementation, syntax, nor
          semantics are 100% endorsed by Larry Wall.  So any of these
          may be changed at some point in the future.

     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
          DDDDeeeeccccllllaaaarrrraaaattttiiiioooonnnn ooooffff oooovvvveeeerrrrllllooooaaaaddddeeeedddd ffffuuuunnnnccccttttiiiioooonnnnssss

              package Number;
              %OVERLOAD = (
                  "+" => \&add,
                  "*=" => "muas"
              );

          declares function _N_u_m_b_e_r::_a_d_d() for addition, and method
          _m_u_a_s() in the "class" Number (or one of its base classes)
          for the assignment form *= of multiplication.  Legal values
          of this hash array are values legal inside &{ ... } call, so
          the name of a subroutine, a reference to a subroutine, or an
          anonymous subroutine will all work.

          The subroutine $OVERLOAD{"+"} will be called to execute
          $a+$b if $a is a reference to an object blessed into the
          package Number, or $a is not an object from a package with
          defined mathemagic addition, but $b is a reference to a
          Number.  It can be called also in other situations, like
          $a+=7, or $a++.  See the section on _M_A_G_I_C _A_U_T_O_G_E_N_E_R_A_T_I_O_N.
          (Mathemagical methods refer to methods triggered by an
          overloaded mathematical operator.)







     Page 1                                          (printed 6/30/95)






     PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))  UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000))))  PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))



          CCCCaaaalllllllliiiinnnngggg CCCCoooonnnnvvvveeeennnnttttiiiioooonnnnssss ffffoooorrrr BBBBiiiinnnnaaaarrrryyyy OOOOppppeeeerrrraaaattttiiiioooonnnnssss

          The functions in values %OVERLOAD are called with three (in
          one particular case with four, see the section on _L_a_s_t
          _R_e_s_o_r_t) arguments.  If the corresponding operation is
          binary, then the first two arguments are the two arguments
          of the operation.  However, due to general object calling
          conventions, the first argument should be always an object
          in the package, so in the situation of 7+$a, the order of
          arguments is interchanged.  Most probably it does not matter
          for implementation of the addition method, but whether the
          arguments are reversed is vital for the subtraction method.
          The subroutine can query this information by examining the
          third argument, which can take three different values:

          FALSE  the order of arguments is as in the current
                 operation.

          TRUE   the arguments are reversed.

          undef  the current operation is an assignment variant (as in
                 $a+=7), but the usual function is called instead.
                 This additional information can be used to generate
                 some optimizations.

          CCCCaaaalllllllliiiinnnngggg CCCCoooonnnnvvvveeeennnnttttiiiioooonnnnssss ffffoooorrrr UUUUnnnnaaaarrrryyyy OOOOppppeeeerrrraaaattttiiiioooonnnnssss

          Unary operation are considered binary operations with the
          second argument being undef.  Thus $OVERLOAD{"++"} is called
          with arguments ($a,undef,'') when $a++ is executed.

          OOOOvvvveeeerrrrllllooooaaaaddddaaaabbbblllleeee OOOOppppeeeerrrraaaattttiiiioooonnnnssss

          The following keys of %OVERLOAD are recognized:

          o+ _A_r_i_t_h_m_e_t_i_c _o_p_e_r_a_t_i_o_n_s

                   "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
                   "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",

               For these operations a substituted non-assignment
               variant can be called if the assignment variant is not
               available.  Methods for operations "+", "-", "+=", and
               "-=" can be called to automatically generate increment
               and decrement methods.  The operations "-" can be used
               to autogenerate missing methods for unary minus or abs.

          o+ _C_o_m_p_a_r_i_s_o_n _o_p_e_r_a_t_i_o_n_s

                   "<",  "<=", ">",  ">=", "==", "!=", "<=>",
                   "lt", "le", "gt", "ge", "eq", "ne", "cmp",




     Page 2                                          (printed 6/30/95)






     PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))  UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000))))  PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))



               If the corresponding "spaceship" variant is available,
               it can be used to substitute for the missing operation.
               During sorting arrays, cmp is used to compare values
               subject to %OVERLOAD.

          o+ _B_i_t _o_p_e_r_a_t_i_o_n_s

                   "&", "^", "|", "neg", "!", "~",

               "neg" stands for unary minus.  If the method for neg is
               not specified, it can be autogenerated using on the
               method for subtraction.

          o+ _I_n_c_r_e_m_e_n_t _a_n_d _d_e_c_r_e_m_e_n_t

                   "++", "--",

               If undefined, addition and subtraction methods can be
               used instead.  These operations are called both in
               prefix and postfix form.

          o+ _T_r_a_n_s_c_e_n_d_e_n_t_a_l _f_u_n_c_t_i_o_n_s

                   "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",

               If abs is unavailable, it can be autogenerated using
               methods for "<" or "<=>" combined with either unary
               minus or subtraction.

          o+ _B_o_o_l_e_a_n, _s_t_r_i_n_g _a_n_d _n_u_m_e_r_i_c _c_o_n_v_e_r_s_i_o_n

                   "bool", "\"\"", "0+",

               If one or two of these operations are unavailable, the
               remaining ones can be used instead.  bool is used in
               the flow control operators (like while) and for the
               ternary "?:" operation.  These functions can return any
               arbitrary Perl value.  If the corresponding operation
               for this value is overloaded too, that operation will
               be called again with this value.

          o+ _S_p_e_c_i_a_l

                   "nomethod", "fallback", "=",

               see the section on _S_P_E_C_I_A_L _K_E_Y_S _O_F %_O_V_E_R_L_O_A_D.

          See the section on _F_a_l_l_b_a_c_k for an explanation of when a
          missing method can be autogenerated.

     SSSSPPPPEEEECCCCIIIIAAAALLLL KKKKEEEEYYYYSSSS OOOOFFFF %%%%OOOOVVVVEEEERRRRLLLLOOOOAAAADDDD
          Three keys are recognized by Perl that are not covered by



     Page 3                                          (printed 6/30/95)






     PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))  UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000))))  PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))



          the above description.

          LLLLaaaasssstttt RRRReeeessssoooorrrrtttt

          $OVERLOAD{"nomethod"} is a reference to a function of four
          parameters.  If defined, it is called when the overloading
          mechanism cannot find a method for some operation.  The
          first three arguments of this function coincide with
          arguments for the corresponding method if it were found, the
          fourth argument is the key of %OVERLOAD corresponding to the
          missing method.  If several methods are tried, the last one
          is used.  Say, 1-$a can be equivalent to

                  &{ $Pack::OVERLOAD{"nomethod"} }($a,1,1,"-").

          If some operation cannot be resolved, and there is no
          $OVERLOAD{"nomethod"}, then an exception will be raised via
          _d_i_e() -- unless $OVERLOAD{"fallback"} is true.

          FFFFaaaallllllllbbbbaaaacccckkkk

          $OVERLOAD{"fallback"} governs what to do if a method for a
          particular operation is not found.  Three different cases
          are possible depending on value of $OVERLOAD{"fallback"}:

          o+ undef         Perl tries to use a substituted method (see
                          the section on _M_A_G_I_C _A_U_T_O_G_E_N_E_R_A_T_I_O_N).  If
                          this fails, it then tries to calls
                          $OVERLOAD{"nomethod"}; if missing, an
                          exception will be raised.

          o+ TRUE          The same as for the undef value, but no
                          exception is raised.  Instead, it silently
                          reverts to what it would have done were
                          there no %OVERLOAD is present.

          o+ defined, but FALSE
                          No autogeneration is tried.  Perl tries to
                          call $OVERLOAD{"nomethod"}, and if this is
                          missing, raises an exception.

          CCCCooooppppyyyy CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr

          $OVERLOAD{"="} is a reference to a function with three
          arguments, i.e., it looks like a usual value of %OVERLOAD.
          What is special about this subroutine is that it should not
          return a blessed reference into a package (as most other
          methods are expected to), but rather a freshly made copy of
          its dereferenced argument (see the section on _B_U_G_S, though).
          This operation is called in the situations when a mutator is
          applied to a reference that shares its object with some
          other reference, such as



     Page 4                                          (printed 6/30/95)






     PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))  UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000))))  PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))



                  $a=$b;
                  $a++;

          To make this change to $a and not to change $b, a freshly
          made copy of $$a is made, and $a is assigned a reference to
          this object.  This operation is executed during $a++, (so
          before this $$a coincides with $$b), and only if ++ is
          expressed via  $OPERATOR{'++'} or $OPERATOR{'+='}.  Note
          that if this operation is expressed via '+', i.e., as

                  $a=$b;
                  $a=$a+1;

          then $$a and $$b do not appear as lvalues.

          If the copy constructor is required during execution of some
          mutator, but $OPERATOR{'='} is missing, it can be
          autogenerated as a string copy if an object of the package
          is a plain scalar.

     MMMMAAAAGGGGIIIICCCC AAAAUUUUTTTTOOOOGGGGEEEENNNNEEEERRRRAAAATTTTIIIIOOOONNNN
          If a method for an operation is not found, and
          $OVERLOAD{"fallback"} is TRUE or undefined, Perl tries to to
          autogenerate a substitute method for the missing operation
          based on defined operations.  Autogenerated method
          substitutions are possible for the following operations:

          _A_s_s_i_g_n_m_e_n_t _f_o_r_m_s _o_f _a_r_i_t_h_m_e_t_i_c _o_p_e_r_a_t_i_o_n_s
                          $a=+$b can use the $OVERLOAD{"+"} method if
                          $OVERLOAD{"+="} is not defined.

          _C_o_n_v_e_r_s_i_o_n _o_p_e_r_a_t_i_o_n_s
                          String, numeric, and boolean conversion are
                          calculated in terms of one another if not
                          all of them are defined.

          _I_n_c_r_e_m_e_n_t _a_n_d _d_e_c_r_e_m_e_n_t
                          The ++$a operation can be expressed in terms
                          of $a+=1 or $a+1, and $a-- in terms of $a-=1
                          and $a-1.

          abs($a)         can be expressed in terms of $a<0 and -$a
                          (or 0-$a).

          _U_n_a_r_y _m_i_n_u_s     can be expressed in terms of subtraction.

          _C_o_n_c_a_t_e_n_a_t_i_o_n   can be expressed in terms of string
                          conversion.

          _C_o_m_p_a_r_i_s_o_n _o_p_e_r_a_t_i_o_n_s
                          can be expressed in terms of its "spaceship"
                          counterpart: either <=> or cmp:



     Page 5                                          (printed 6/30/95)






     PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))  UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000))))  PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))



                              <, >, <=, >=, ==, !=      in terms of
                          <=>
                              lt, gt, le, ge, eq, ne    in terms of
                          cmp

          _C_o_p_y _o_p_e_r_a_t_o_r   can be expressed in terms of assignment to
                          the dereferenced value, if this value is
                          scalar but not a reference.

     WWWWAAAARRRRNNNNIIIINNNNGGGG
          The restriction for the comparison operation is that even
          if, for example, `cmp' should return a blessed reference,
          the autogenerated `lt' function will produce only a standard
          logical value based on the numerical value of the result of
          `cmp'.  In particular, a working numeric conversion is
          needed in this case (possibly expressed in terms of other
          conversions).

          Similarly, .=  and x= operators lose their mathemagical
          properties if the string conversion substitution is applied.

          When you _c_h_o_p() a mathemagical object, it becomes promoted
          to a string first, and its mathemagical qualities is lost.
          The same can happen with other operations as well.

     IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
          The table of methods for all operations is cached as a magic
          for the symbol table hash of the package.  It is rechecked
          for changes of %OVERLOAD and @ISA only during blessing; so
          if it is changed dynamically, you'll need an additional fake
          blessing to update the table.

          (Every SVish thing has a magic queue, and a magic is an
          entry in that queue.  This is how a single variable may
          participate in multiple forms of magic simultaneously.  For
          instance, environment variables regularly have two forms at
          once: their %ENV magic and their taint magic.)

          If an object belongs to a package with %OVERLOAD, it carries
          a special flag.  Thus the only speed penalty during
          arithmetic operations without overload is the check of this
          flag.

          In fact, if no %OVERLOAD is ever accessed, there is almost
          no overhead for overloadable operations, so most programs
          should not suffer measurable performance penalties.
          Considerable effort was made minimize overhead when
          %OVERLOAD is accessed and the current operation is
          overloadable but the arguments in question do not belong to
          packages with %OVERLOAD.  When in doubt, test your speed
          with %OVERLOAD and without it.  So far there have been no
          reports of substantial speed degradation if Perl is compiled



     Page 6                                          (printed 6/30/95)






     PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))  UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000))))  PPPPEEEERRRRLLLLOOOOVVVVLLLL((((1111))))



          with optimization turned on.

          There is no size penalty for data if there is no %OVERLOAD.

          The copying like $a=$b is shallow; however, a one-level-deep
          copying is carried out before any operation that can imply
          an assignment to the object $b (or $a) refers to, like $b++.
          You can override this behavior by defining your copy
          constructor (see the section on _C_o_p_y _C_o_n_s_t_r_u_c_t_o_r).

          It is expected that arguments to methods that are not
          explicitly supposed to be changed are constant (but this is
          not enforced).

     AAAAUUUUTTTTHHHHOOOORRRR
          Ilya Zakharevich <_i_l_y_a@_m_a_t_h._m_p_s._o_h_i_o-_s_t_a_t_e._e_d_u>.

     DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
          When Perl is run with the ----DDDDoooo switch or its equivalent,
          overloading induces diagnostic messages.

     BBBBUUUUGGGGSSSS
          Because it's used for overloading, the per-package
          associative array %OVERLOAD now has a special meaning in
          Perl.

          Although the copy constructor is specially designed to make
          overloading operations with references to an array simpler,
          as it now works it's useless for this because a subroutine
          cannot return an array in the same way as it returns a
          scalar (from the point of view of Perl internals).  Expect a
          change of interface for the copy constructor.

          As shipped, %OVERLOAD is not inherited via the @ISA tree.  A
          patch for this is available from the author.

          This document is confusing.


















     Page 7                                          (printed 6/30/95)